Code Like You Speak

Ok, so I wrote a post about why I use long variable names, where I discussed how it is very easy to use long filenames with today’s IDEs. As I code more and more I realize how I want to write like I speak.

As I try to read other people’s code, I have to wonder if they could even understand it themselves if they went six months without touching it.

For example, lets say I am working with a database that has phone numbers and for each phone number I want to do check if it is valid:

Example 1

PhoneNumber p = new PhoneNumber("555-555-5555");
if (p.isValid())
{
    // do something
} else
{
    // Do something different
}

There is nothing wrong with the above code. It even makes sense, mostly because the first line where p is created is right next to the if statement. But of course that is not always the case.

Maybe I have dozens of objects for different database attributes including multiple ojects that start with ‘p’: PhoneNumber, PartList, PersonID, and they all have an isValid() method and those objects are created elsewhere in the code, who knows where. Also, your isValid() function in PhoneNumber checks if the PhoneNumber is formatted correctly, but the isValid() function in PartList checks if it is a valid part in the database and the isValid() function in PersonID does something different, now the above code would be more confusing, especially to some one else reading it (or to yourself six months after writing it).

if (p.isValid())
{
    // do something
} else
{
    // Do something different
}

So if we don’t have the declaration right next to the code, it is hard to understand…

You might say, “Load it in a debugger and just look…why is it so hard?”

My response is this. “What about your Team Leads for you Tech Support team? What about your documentation team? They may have that has access to read the code but they don’t have the tools or know how to compile it. But they may need to see your code to get their job done. And I don’t want to offend your project managers, but there sure are a lot of Project Managers that either never had the ability or have lost the skill to compile code.”

So someone else reading your code is lost. What does p represent? PhoneNumber, PartList, PersonId? What is the object? What does isValid() check for on this object?

So lets code like we speak. First you should say what we really want to do in your language. The sentence below is a valid English sentence and anybody who speaks English can understand it.

If the current phone number is formatted correctly, do something, else do something different.

Well, what if the code were written like this:

// This could be anywhere in code
PhoneNumber theCurrentPhoneNumber = new PhoneNumber("555-555-5555");

// A code like you speak if statement
if (theCurrentPhoneNumber.isFormattedCorrectly())
{
    // do something
} else
{
    // do something different
}

See how it is in “code like you speak” format?

So you may here different theories about writing code and whether to document with comments or not document and have clear code. I am for the theory that when you write your code you should assume that the person reading your code:
1. Doesn’t understand code.
2. Has no technical skills
3. Has an average IQ (in the 90s).
4. Is the worst technical ever who has to document your code…
etc, etc, etc…

So that is why “Code like you speak” is a great way to code. If your technical writer reads the first example, he is confused, but if he read the second, he fully understands the idea what it going one.

Now, it is important that you don’t over do it. You don’t need to have perfect English. Broken English is fine. As you practice you will get better at it. As you get better at it, your code becomes more readable and others can work on it easier. This is especially usefully when working in teams, or one a community-developed open source application.

Don’t go overboard! I mean, there is not reason to define the word “othewise” to replace “else”. If you did that, you may actually confuse veteran developers.

// In a header somewhere...
#define otherwise else

// This could be anywhere in code
PhoneNumber theCurrentPhoneNumber = new PhoneNumber("555-555-5555");

// A code like you speak if statement
if (theCurrentPhoneNumber.isFormattedCorrectly())
{
    // do something
}
otherwise
{
    // do something different
}

However, if the “Code like you speak” development style takes off, the above may not be so overboard, and may become a standard practice to define many English synonyms to help one code in a more clear and understandable method.

One might argue that because not every one speaks english, a language barrier would be more likely, and I would have to disagree. If you code like you speak, someone who doesn’t speak your language could still figure it out a lot faster using something like a language translation tool (such as google’s or babblefish’s) than they could by trying to figure out what a random object is.

As for other style guide information, there are lots of style guides. If you need one and don’t have one, start with this one:
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml